.Dd October 27, 2015
.Dt ENGINES.JSON 5
.Os
.Sh NAME
.Nm engines.json
.Nd Sylvan engine configuration file
.Sh DESCRIPTION
.Nm
is the chess engine configuration file for
.Xr sylvan-cli 6 .
An engine configuration defines a name, a command, a working directory and
many other options.
Engine configurations can be used in
.Xr sylvan-cli 6
with the
.Cm conf
command-line option.
.Pp
Engine configurations are defined in JavaScript Object Notation (JSON) format.
See
.Sx JSON FORMAT .
.Sh JSON FORMAT
JavaScript Object Notation (JSON) is a text-based format for structured data.
JSON is a subset of ECMAScript (JavaScript).
.Ss Values
A JSON value must be one of:
.Ar object ,
.Ar array ,
.Ar number ,
.Ar string ,
.Cm false ,
.Cm true
or
.Cm null .
.Ss Objects
An
.Ar object
is structure of
.Pf name- Ar value
pairs enclosed in curly brackets.
A name is a
.Ar string .
Name and value are separated by a single colon.
Pairs are separated by commas.
.Pp
Example objects would be:
.Bd -literal -offset indent
{ "Finland" : ".fi", "Sweden" : ".se" }

{
  "firstName" : "JC",
  "lastName"  : "Denton",
  "age"       : 28,
  "languages" : [ "English", "French", "Spanish" ]
}
.Ed
.Ss Arrays
An
.Ar array
is a structure of zero or more
.Ar values
enclosed in square brackets.
Values are separated by commas.
.Pp
Example arrays would be:
.Bd -literal -offset indent
[ "Sylvan", "" ]

[
  [ 1, 0, 0 ],
  [ 0, 1, 0 ],
  [ 0, 0, 1 ]
]
.Ed
.Ss Numbers
A
.Ar number
consists of an integer part and optional fractional and/or exponent part.
The integer part can be prefixed with a minus sign.
Fractional part is a decimal point followed by one or more digits.
Exponent part begins with a letter E in upper or lowercase which may be
followed by a plus or minus sign.
The E and optional sign are followed by one or more digits.
.Pp
Octal and hex forms are not allowed.
.Pp
Example numbers would be:
.Bd -literal -offset indent
128
-1.04
2e32
-18E-20
.Ed
.Ss Strings
A
.Ar string
is sequence of characters enclosed in quotation marks.
All Unicode characters may be placed within the quotation marks except
for the characters that must be escaped: quotation mark, backslash, and
control characters.
.Pp
Available two-character escape sequences are as follows:
.Pp
.Bl -tag -width Ds -offset indent -compact
.It Cm \e\e
Backslash character.
.It Cm \e/
Forward slash character.
.It Cm \e\(dq
Quotation mark.
.It Cm \eb
Bell character.
.It Cm \ef
Form feed character.
.It Cm \en
Line feed character.
.It Cm \et
Vertical tab character.
.It Cm \eu Ns Ar num
Unicode character where
.Ar num
is a four hexadecimal digits that encode the character's code point.
.El
.Pp
Example strings would be:
.Bd -literal -offset indent
"Hello, world!"

"Please place all items \e"carefully\e" in bins."

"\eu03a6 is one of the letters of Greek alphabet."
.Ed
.Sh ENGINE CONFIGURATION
The configuration file consist of an
.Ar array
of
.Ar objects .
Each object defines a single engine configuration.
Required options for each engine configuration are:
.Bl -tag -width Ds
.It Ic name No \&: Ar string
The name of the engine.
.It Ic command No \&: Ar string
The engine command.
.It Ic protocol No \&: \(dquci\(dq | \(dqxboard\(dq
The chess engine protocol used by this engine.
.El
.Pp
Other available options for an engine configuration are:
.Bl -tag -width Ds
.It Ic workingDirectory No \&: Ar string
The working directory of the engine.
.It Ic stderrFile No \&: Ar string
File where the engine's standard error output is redirected.
.It Ic initStrings No \&: Ar array No of Ar string
Array of strings sent to the engine's standard input at startup.
.It Ic whitepov No \&: Cm true | Cm false
When
.Cm true
invert the engine's scores when it plays black.
The default is
.Cm false .
.Pp
This option should be used with engines that always report scores from
white's perspective.
.It Ic ponder No \&: Cm true | Cm false
When
.Cm true
enable pondering if the engine supports it.
The default is
.Cm false .
.El
.Sh EXAMPLES
A minimal engine configuration file for the Sloppy chess engine:
.Bd -literal -offset indent
[
  {
    "name": "Sloppy",
    "command": "sloppy",
    "protocol": "xboard"
  }
]
.Ed
.Pp
Using the above engine configuration file with the
.Cm conf
command-line option:
.Pp
.Dl $ sylvan-cli \-engine conf=Sloppy -engine conf=Sloppy -each tc=40/60 -rounds 10
.Sh SEE ALSO
.Xr sylvan-cli 6
.Rs
.%R RFC 4627
.%T "The application/json Media Type for JavaScript Object Notation (JSON)"
.%D July 2006
.Re
